Planetfall OXP by Thargoid and phkb
===================================

This OXP is designed to be extendable to add new locations on planets and moons, and to give locations for mission events to take place. For this a number of variables are made available within the scripting. These scripts are accessible from any javascript worldscript within a game OXP.

worldScripts.PlanetFall2.lastPlanet - this is the last planet to be approached.
worldScripts.PlanetFall2.lastPlanetType - the type of the last planet landed on ("Prime", "Sub" or "Moon") or approached ("Sun" or "GasGiant").
worldScripts.PlanetFall2.planetCount - how many planets (bodies with atmospheres) in the system.
worldScripts.PlanetFall2.moonCount - how many moons (bodies without atmospheres) in the system.

When the player is planet-side, and they utilise the transit system, they could end up a long way from where they initially landed. To know when the player is not near their ship, use the following function:

worldScripts.PlanetFall2.playerShipIsLocal()

This will return true if the player is near their ship, or false if they're at a location other than where their ship is parked.

For expansion purposes, three example OXPs are also available.

* PlanetFall Mission - Taxi - This example mission gives intra-system taxi ride offers (available on 25% of the manifest (F5-F5) screens whilst docked). it shows how some of the above variables can be used to determine where the player is docked and what state the system is in.
* PlanetFall Link - Black Monks (requires the full BlackMonks OXP)
* PlanetFall Link - hoOpy Casino (requires the full hoOpy casino OXP)

These last two link OXPs add new planetary locations, allowing Black Monk and HoOpy Casino OXP mission offerings when their full OXPs are also installed on the system. 

Scenario 1: Adding new locations into the pool of locations
-----------------------------------------------------------
To add additional locations into the pool of default locations, use a shipdata.plist entry as in the two above examples. For example, the entry for the hoOpy casino on the main planets is:

	"planetFall2_mainSurface_hoopyCasino" =	{
		like_ship = "planetFall2_genericSurface";
		name = "CoachWhip hOopy Casino"; 
		roles = "planetFall2_mainSurface_hoopyCasino planetFall2_mainSurface station(0) planetFall2_surface planetFall_surface";
	};

The first role should be replaced by the appropriate one (one unique to this location), and the other four are also necessary. For locations on additional (sub, not main) planets, replace "main" with "sub", and for those on moons replace "main" with "moon". The location will be called via the planetFall2_<main/sub/moon>Surface role.

You can control the when the custom location will spawn by using these values in script_info:
	spawn_chance: decimal percentage chance of space (eg 0.2 = 20%). Chance will be the same for any given system. Scaled with TechLevel of system.
	seed: seed value for randomisation process.
	always_spawn: boolean to indicate this location should always spawn.

Scenario 2: Replacing all default locations with a single overridden role
-------------------------------------------------------------------------
If the variable worldScripts.PlanetFall2.planetFallOverride is set to true, only external OXP locations are spawned. These are shipdata entries with one of the planetFall2_<main/sub/moon>Surface_externalOXP roles. Please use sparingly, and don't forget to set it back to false once you've finished with it!

Also the ownProperties ".solarGasGiant" and ".isGasGiant" are both available for recognition of gas giant planets (for Frame & Commander Cheyn, plus anyone else who may want to use them).

Lastly the ownProperties of ".PFNoLand" and ".PFNoLandQuiet" are added to give warnings (or not) if approaching OXP planetary objects where landing should not be allowed, for example Tionisla pulsar.

If you want to use a role other than the default roles listed above, use worldScripts.PlanetFall2.overrideRole to set the role. Once set, that specific role will be used to create landing sites (as long as worldScripts.PlanetFall2.planetFallOverride is set to true). Care should of course be taken that a second OXP may also make a similar setting. If the variable is not set then the standard default roles of planetFall2_<main/sub/moon>Surface_externalOXP are used.

While the systemWillPopulate world event is best suited for setting the planetFallOverride flag and the overrideRole, problems with sequencing can mean
the values are not set at the right time. To work around this, an additional function call is required. In your script file, normally in the "startUp"
world event function, add the following line:

	worldScripts.PlanetFall2.$addPrepopulationFunction(this.name, "extraPopulation");

Then add the function "extraPopulation" to your script:

	this.extraPopulation = function() {
		if (...perform checks to see whether we need to override PlanetFall...) {
			// if so...
			worldScripts.PlanetFall2.planetFallOverride = true;
			// optionally set the override role
			worldScripts.PlanetFall2.overrideRole = "mySpecialPlanetFallRole";
		}
	}

This will ensure the values are set in the correct order.

Scenario 3: Disabling all planetary locations
---------------------------------------------
If you want to disable all planetary locations for a particular system, so that nothing is set up on any planet, set worldScripts.PlanetFall2.disable = true in the shipWillEnterWitchspace world event prior to jumping into the system where you want to disable planetary locations.

Scenario 4: Adding custom planets, but not with the "Additional Planets OXP"
----------------------------------------------------------------------------
PlanetFall 2.0 is designed to integrate with the Additional Planets OXP. If you are adding a planet or moon outside of that OXP, you need to run the following code during the systemWillPopulate world event:

	worldScripts.PlanetFall2.$addExtraPlanetDocksForPlanet(myPlanet);

If you don't have a planet entity to work with yet (because the creation takes place in a system.setPopulator callback, for instance), but you do know the position the planet will have, the radius of the planet, and whether it has an atmosphere, use the following code:

	worldScripts.PlanetFall2.$addExtraPlanetDocks(position, radius, hasAtmosphere, false);

However, do *not* run this command inside a system.setPopulator callback script, as no planetary locations will be added in that scenario.

Scenario 5: Adding a fully customised and predefined set of landing sites
-------------------------------------------------------------------------
A fully customised system can be defined. See the "Custom Systems.txt" document for more details.
